popdemo (version 0.2-3)

inertia.tfsens : Calculate sensitivity of inertia using transfer functions

Description

Calculate the sensitivity of inertia to perturbations to a population projection matrix (PPM) model using a transfer function method.

Usage

inertia.tfsens(A, d=NULL, e=NULL, vector="n", bound=NULL,   startval=0.001, tolerance=1e-10, return.fit=FALSE, plot.fit=FALSE) inertia.tfsensmatrix(A, vector="n", bound=NULL, startval=0.001, tolerance=1e-10)

Arguments

A

a square, primitive, nonnegative matrix of any dimension

d,e

numeric vectors that determine the perturbation structure (see details).

vector

(optional) a specified initial age/stage distribution of class vector or class matrix with which to calculate case-specific sensitvity of inertia.

bound

(optional) specifies whether an upper or lower bound should be calculated (see details).

startval

inertia.tfsens calculates the limit of the derivative of the transfer function as lambda approaches the dominant eigenvalue of A (see details). startval provides a starting value for the algorithm: the smaller startval is, the quicker the algorithm should converge.

tolerance

the tolerance level for determining convergence (see details).

return.fit

if TRUE (and only if d and e are specified), the lambda and sensitivity values obtained in the convergence algorithm are returned alongside the calculated sensitivity of inertia.

plot.fit

if TRUE then convergence of the algorithm is plotted as sensitivity~lambda.

Value

For inertia.tfsens, the sensitivity of inertia (or its bound) to the specified perturbation structure. If return.fit=TRUE, a list containing components:

sens

the sensitivity of population inertia (or its bound) to the specified perturbation structure

lambda.fit

the lambda values obtained in the fitting process

sens.fit

the sensitivity values obtained in the fitting process

For inertia.tfsensmatrix, a matrix containing sensitivity of inertia to each seperate element of A.

Details

inertia.tfsens and inertia.tfsensmatrix differentiate a transfer function to find sensitivity of inertia to perturbation.

If vector="n" then either bound="upper" or bound="lower" must be specified, so calculating the sensitivity of the upper or lower bound on population inertia respectively. Specifying vector overrides calculation of a bound, and will yield sensitivity of case-specific inertia.

inertia.tfsens may be used to find sensitivity of a particular perturbation structure. A desired perturbation structure can be determined by d%*%t(e). Therefore, the rows to be perturbed are determined by d and the columns to be perturbed are determined by e. The specific values in d and e will determine the relative perturbation magnitude. So for example, if only entry [3,2] of a 3 by 3 matrix is to be perturbed, then d = c(0,0,1) and e = c(0,1,0). If entries [3,2] and [3,3] are to be perturbed with the magnitude of perturbation to [3,2] half that of [3,3] then d = c(0,0,1) and e = c(0,0.5,1). d and e may also be expressed as column vectors of class matrix, e.g. d = matrix(c(0,0,1), ncol=1), e = matrix(c(0,0.5,1), ncol=1). See Hodgson et al. (2006) for more information on perturbation structures.

inertia.tfsensmatrix returns a matrix of sensitivity values for observed transitions, where the sensitivity of each matrix element is evaluated seperately.

The formula used by inertia.tfsens and inertia.tfsensmatrix cannot be evaluated at lambda-max, therefore it is necessary to find the limit of the formula as lambda approaches lambda-max. This is done using a bisection method, starting at a value of lambda-max + startval. startval should be small, to avoid the potential of false convergence. The algorithm continues until successive sensitivity calculations are within an accuracy of one another, determined by tolerance: a tolerance of 1e-10 means that the sensitivity calculation should be accurate to 10 decimal places. However, as the limit approaches lambda-max, matrices become uninvertible (singular): if matrices are found to be singular then tolerance should be relaxed and made larger.

For inertia.tfsens, there is an extra option to return and/or plot the above fitting process using return.fit=TRUE and plot.fit=TRUE respectively.

References

Hodgson et al. (2006) J. Theor. Biol., 70, 214-224.

See Also

Related: inertia

Transfer function methods: inertia.tfa, inertia.tfamatrix

Examples

    # Create a 3x3 matrix
    A <- matrix(c(0,1,2,0.5,0.1,0,0,0.6,0.6), byrow=TRUE, ncol=3)
    A

    # Create an initial stage structure    
    initial <- c(1,3,2)
    initial

    # Calculate the sensitivity matrix for the upper bound on inertia
    inertia.tfsensmatrix(A, bound="upper",tolerance=1e-7)

    # Calculate the sensitivity of simultaneous perturbation to 
    # A[1,3] and A[2,3] for the lower bound on inertia
    inertia.tfsens(A, d=c(1,0,0), e=c(0,1,1), bound="lower")

    # Calculate the sensitivity of simultaneous perturbation to 
    # A[1,3] and A[2,3] for specified initial stage structure
    # and return and plot the fitting process
    inertia.tfsens(A, d=c(1,0,0), e=c(0,1,1), vector=initial,tolerance=1e-7,
                   return.fit=TRUE,plot.fit=TRUE)